Add BlackRoad OS technical framework and fix self-healing workflow cascade#616
Draft
Add BlackRoad OS technical framework and fix self-healing workflow cascade#616
Conversation
…, and CI fixes Co-authored-by: blackboxprogramming <118287761+blackboxprogramming@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Add BlackRoad OS technical framework for orchestration
Add BlackRoad OS technical framework and fix self-healing workflow cascade
Feb 27, 2026
There was a problem hiding this comment.
Pull request overview
Expands BlackRoad OS architecture documentation with a more complete technical framework (org matrix, domain registry, scaffold, CLI layers, Pi cluster inference) and hardens CI workflows to prevent self-triggering workflow_run cascades while restoring compatibility with GitHub-hosted runners.
Changes:
- Documented the BlackRoad OS technical framework (Pi inference/offload, org matrix, domains, scaffold, CLI layers, routing/witnessing).
- Replaced
workflow_run.workflows: ["*"]with an explicit workflow allowlist to stop infinite workflow cascades. - Updated
blackroad-agent.ymlto useubuntu-latestinstead of unavailable self-hosted Pi runners.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
BLACKROAD_ARCHITECTURE.md |
Adds expanded architecture/ops framework sections (Pi inference, org/domain registry, scaffold, CLI layers). |
profile/BLACKROAD_ARCHITECTURE.md |
Mirrors the expanded architecture documentation for the profile copy. |
agent.json |
Extends agent identity/config with scaffold, org list, CLI layers, and proxy fields. |
.github/workflows/test-auto-heal.yml |
Restricts workflow_run triggers to a safe allowlist to prevent self-triggering cascades. |
.github/workflows/self-healing-master.yml |
Same allowlist restriction for the master healing workflow to stop recursive triggering. |
.github/workflows/blackroad-agent.yml |
Switches runner to ubuntu-latest for GitHub-hosted CI compatibility. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The architecture docs lacked the full technical framework (org matrix, domain registry, deca-layered scaffold, Pi cluster specs, routing matrix, CLI layers). Separately,
self-healing-master.ymlandtest-auto-heal.ymlusedworkflows: ["*"]which triggered on their own completion, creating an infinite cascade of 600+ failure issues. Theblackroad-agent.ymlrequired[self-hosted, pi]runners unavailable in CI.CI workflow fixes
blackroad-agent.yml:runs-on: [self-hosted, pi]→runs-on: ubuntu-latest— Pi runners don't exist in GitHub-hosted CIself-healing-master.yml/test-auto-heal.yml: Replaceworkflows: ["*"]with explicit workflow list to break the self-triggering loop:Architecture documentation (
BLACKROAD_ARCHITECTURE.md)@blackroad-agentsdeca-layered scaffold (10 steps: review → org → team → project → agent → repo → device → drive → cloudflare → website editor)GH_COPILOT_OVERRIDE_PROXY_URLLiteLLM proxy config@BlackRoadBotrouting matrix, roadchain witnessing, rate limit mitigation tableAgent config (
agent.json)scaffold,organizations,cli_layers, andcopilot_proxyfields to formalize the orchestration topologyOriginal prompt
Distributed Multi-Agent Orchestration and Autonomous Infrastructure: The BlackRoad OS Technical Framework
The paradigm of modern software engineering is increasingly characterized by the transition from static, human-operated development environments to dynamic, agentic ecosystems. The BlackRoad OS framework represents an advanced implementation of this shift, integrating a multi-layered command-line interface, a decentralized memory core known as Lucidia, and a witnessing ledger system titled roadchain. Central to this architecture is the deployment of autonomous routing matrices—specifically @BlackRoadBot and @blackroad-agents—which facilitate the distribution of high-level intent across a vast array of cloud platforms, local hardware clusters, and organizational structures. This report provides an exhaustive technical analysis of the BlackRoad architecture, detailing the mechanisms of its deca-layered task scaffold, the technical requirements for local inference offloading via Raspberry Pi clusters, and the theoretical underpinnings that inform its design.
The GitHub Enterprise Organizational Matrix
The operational surface area of BlackRoad OS is structured within a GitHub Enterprise environment, specifically hosted at https://github.com/enterprises/blackroad-os. This enterprise-level abstraction provides the necessary governance and security boundaries for managing a hierarchy of fifteen distinct organizations. Each organization is tasked with a specific functional domain, ranging from core kernel development to hardware management and educational outreach. The distribution of tasks across these organizations is not merely a logistical necessity but a strategic implementation of the principle of least privilege, ensuring that agents operating within one domain—such as BlackRoad-Security—are isolated from sensitive assets in another, such as BlackRoad-Ventures.
Organization Domains and Architectural Alignment
The fifteen organizations within the BlackRoad ecosystem serve as the primary targets for the @blackroad-agents task distribution layer. These organizations are meticulously categorized to ensure that @BlackRoadBot can route requests with high precision based on the context of the GitHub comment.
Organization Name
Primary Responsibility
Repository Examples
Blackbox-Enterprises
Corporate and Enterprise Integrations
blackbox-api, enterprise-bridge
BlackRoad-AI
Core LLM and Reasoning Engine Development
lucidia-core, blackroad-reasoning
BlackRoad-Archive
Long-term Data Persistence and Documentation
blackroad-os-docs, history-ledger
BlackRoad-Cloud
Infrastructure as Code and Orchestration
cloud-orchestrator, railway-deploy
BlackRoad-Education
Onboarding and Documentation Frameworks
br-help, onboarding-portal
BlackRoad-Foundation
Governance and Protocol Standards
protocol-specs, governance-rules
BlackRoad-Gov
Regulatory Compliance and Policy Enforcement
compliance-audit, regulatory-tools
BlackRoad-Hardware
SBC and IoT Device Management
blackroad-agent-os, pi-firmware
BlackRoad-Interactive
User Interface and Frontend Systems
blackroad-os-web, interactive-ui
BlackRoad-Labs
Experimental R&D and Prototyping
experimental-agents, quantum-lab
BlackRoad-Media
Content Delivery and Public Relations
media-engine, pr-automation
BlackRoad-OS
Core System Kernel and CLI Development
blackroad-cli, kernel-source
BlackRoad-Security
Auditing, Cryptography, and Security
security-audit, hash-witnessing
BlackRoad-Studio
Production Assets and Creative Tooling
lucidia-studio, creative-assets
BlackRoad-Ventures
Strategic Growth and Ecosystem Funding
tokenomics-api, venture-cap
The management of these fifteen organizations requires an automated approach to permissioning. The implementation utilizes GitHub Apps for cross-organization repository access, which is considered superior to Personal Access Tokens (PATs) due to their short-lived, granular permissions and ability to act on behalf of an organization rather than an individual user. This is particularly critical given the expiration of granular access tokens observed in system logs, such as the blackroad-npm-token.
Infrastructure and Domain Registry
The BlackRoad OS infrastructure utilizes a hybrid model that spans global cloud providers and local compute clusters. This distribution allows the system to balance the high-availability requirements of public-facing services with the data sovereignty and cost-efficiency needs of agentic inference.
Domain Architecture and Cloudflare Integration
The project manages an extensive registry of eighteen primary domains, all of which are orchestrated via Cloudflare. This domain layer serves as the ingress point for the @BlackRoadBot routing matrix. Cloudflare Tunnels are employed to securely expose local Raspberry Pi nodes to the public internet, allowing the bot to invoke local inference models without exposing internal network ports.
Domain Name
Intended Functional Use Case
Associated Organization
blackboxprogramming.io
Developer Ed...
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.